<!DOCTYPE HTML>
<html lang="en" class="light" dir="ltr">
    <head>
        <!-- Book generated using mdBook -->
        <meta charset="UTF-8">
        <title>The Rustup developer guide</title>
        <meta name="robots" content="noindex">


        <!-- Custom HTML head -->
        
        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="theme-color" content="#ffffff">

        <link rel="icon" href="favicon.svg">
        <link rel="shortcut icon" href="favicon.png">
        <link rel="stylesheet" href="css/variables.css">
        <link rel="stylesheet" href="css/general.css">
        <link rel="stylesheet" href="css/chrome.css">
        <link rel="stylesheet" href="css/print.css" media="print">

        <!-- Fonts -->
        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
        <link rel="stylesheet" href="fonts/fonts.css">

        <!-- Highlight.js Stylesheets -->
        <link rel="stylesheet" href="highlight.css">
        <link rel="stylesheet" href="tomorrow-night.css">
        <link rel="stylesheet" href="ayu-highlight.css">

        <!-- Custom theme stylesheets -->

    </head>
    <body class="sidebar-visible no-js">
    <div id="body-container">
        <!-- Provide site root to javascript -->
        <script>
            var path_to_root = "";
            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
        </script>

        <!-- Work around some values being stored in localStorage wrapped in quotes -->
        <script>
            try {
                var theme = localStorage.getItem('mdbook-theme');
                var sidebar = localStorage.getItem('mdbook-sidebar');

                if (theme.startsWith('"') && theme.endsWith('"')) {
                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                }

                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                }
            } catch (e) { }
        </script>

        <!-- Set the theme before any content is loaded, prevents flash -->
        <script>
            var theme;
            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
            if (theme === null || theme === undefined) { theme = default_theme; }
            var html = document.querySelector('html');
            html.classList.remove('light')
            html.classList.add(theme);
            var body = document.querySelector('body');
            body.classList.remove('no-js')
            body.classList.add('js');
        </script>

        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

        <!-- Hide / unhide sidebar before it is displayed -->
        <script>
            var body = document.querySelector('body');
            var sidebar = null;
            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
            if (document.body.clientWidth >= 1080) {
                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                sidebar = sidebar || 'visible';
            } else {
                sidebar = 'hidden';
            }
            sidebar_toggle.checked = sidebar === 'visible';
            body.classList.remove('sidebar-visible');
            body.classList.add("sidebar-" + sidebar);
        </script>

        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
            <div class="sidebar-scrollbox">
                <ol class="chapter"><li class="chapter-item expanded "><a href="index.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="linting.html"><strong aria-hidden="true">1.1.</strong> Linting</a></li></ol></li><li class="chapter-item expanded "><a href="coding-standards.html"><strong aria-hidden="true">2.</strong> Coding standards</a></li><li class="chapter-item expanded "><a href="version-numbers.html"><strong aria-hidden="true">3.</strong> Version numbers</a></li><li class="chapter-item expanded "><a href="release-process.html"><strong aria-hidden="true">4.</strong> Release process</a></li><li class="chapter-item expanded "><a href="tips-and-tricks.html"><strong aria-hidden="true">5.</strong> Tips and tricks</a></li><li class="chapter-item expanded "><a href="tracing.html"><strong aria-hidden="true">6.</strong> Tracing</a></li></ol>
            </div>
            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
                <div class="sidebar-resize-indicator"></div>
            </div>
        </nav>

        <!-- Track and set sidebar scroll position -->
        <script>
            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
            sidebarScrollbox.addEventListener('click', function(e) {
                if (e.target.tagName === 'A') {
                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
                }
            }, { passive: true });
            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
            sessionStorage.removeItem('sidebar-scroll');
            if (sidebarScrollTop) {
                // preserve sidebar scroll position when navigating via links within sidebar
                sidebarScrollbox.scrollTop = sidebarScrollTop;
            } else {
                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
                var activeSection = document.querySelector('#sidebar .active');
                if (activeSection) {
                    activeSection.scrollIntoView({ block: 'center' });
                }
            }
        </script>

        <div id="page-wrapper" class="page-wrapper">

            <div class="page">
                                <div id="menu-bar-hover-placeholder"></div>
                <div id="menu-bar" class="menu-bar sticky">
                    <div class="left-buttons">
                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                            <i class="fa fa-bars"></i>
                        </label>
                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                            <i class="fa fa-paint-brush"></i>
                        </button>
                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                        </ul>
                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
                            <i class="fa fa-search"></i>
                        </button>
                    </div>

                    <h1 class="menu-title">The Rustup developer guide</h1>

                    <div class="right-buttons">
                        <a href="print.html" title="Print this book" aria-label="Print this book">
                            <i id="print-button" class="fa fa-print"></i>
                        </a>
                        <a href="https://github.com/rust-lang/rustup/tree/master/doc/dev-guide" title="Git repository" aria-label="Git repository">
                            <i id="git-repository-button" class="fa fa-github"></i>
                        </a>

                    </div>
                </div>

                <div id="search-wrapper" class="hidden">
                    <form id="searchbar-outer" class="searchbar-outer">
                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                    </form>
                    <div id="searchresults-outer" class="searchresults-outer hidden">
                        <div id="searchresults-header" class="searchresults-header"></div>
                        <ul id="searchresults">
                        </ul>
                    </div>
                </div>

                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                <script>
                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                    });
                </script>

                <div id="content" class="content">
                    <main>
                        <h1 id="contributing-to-rustup"><a class="header" href="#contributing-to-rustup">Contributing to rustup</a></h1>
<ol>
<li>Fork it!</li>
<li>Create your feature branch: <code>git checkout -b my-new-feature</code></li>
<li>Test it: <code>cargo test --features=test</code></li>
<li><a href="linting.html">Lint it!</a></li>
<li>Commit your changes: <code>git commit -am 'Add some feature'</code></li>
<li>Push to the branch: <code>git push origin my-new-feature</code></li>
<li>Submit a pull request :D</li>
</ol>
<p>For developing on <code>rustup</code> itself, you may want to install into a temporary
directory, with a series of commands similar to this:</p>
<pre><code class="language-bash">cargo build
mkdir home
RUSTUP_HOME=home CARGO_HOME=home target/debug/rustup-init --no-modify-path -y
</code></pre>
<p>You can then try out <code>rustup</code> with your changes by running <code>home/bin/rustup</code>, without
affecting any existing installation. Remember to keep those two environment variables
set when running your compiled <code>rustup-init</code> or the toolchains it installs, but <em>unset</em>
when rebuilding <code>rustup</code> itself.</p>
<p>If you wish to install your new build to try out longer term in your home directory
then you can run <code>cargo dev-install</code> which is an alias in <code>.cargo/config</code> which
runs <code>cargo run -- --no-modify-path -y</code> to install your build into your homedir.</p>
<p>We use <code>rustfmt</code> to keep our codebase consistently formatted. Please ensure that
you have correctly formatted your code (most editors will do this automatically
when saving) or it may not pass the CI tests.</p>
<p>If you are moving, renaming or removing an existing mdBook page, please use mdBook’s
<a href="https://rust-lang.github.io/mdBook/format/configuration/renderers.html#outputhtmlredirect"><code>output.html.redirect</code></a> feature to ensure that the old URL gets redirected.</p>
<p>Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the
Apache-2.0 license, shall be dual licensed as in the README, without any
additional terms or conditions.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="linting"><a class="header" href="#linting">Linting</a></h1>
<p>We use <code>cargo clippy</code> to ensure high-quality code and to enforce a set of best practices for Rust programming.
However, not all lints provided by <code>cargo clippy</code> are relevant or applicable to our project.
We may choose to ignore some lints if they are unstable, experimental, or specific to our project.
If you are unsure about a lint, please ask us in the <a href="https://discord.com/channels/442252698964721669/463480252723888159">rustup Discord channel</a>.</p>
<h2 id="manual-linting"><a class="header" href="#manual-linting">Manual linting</a></h2>
<p>When checking the codebase with <a href="https://doc.rust-lang.org/stable/clippy/index.html"><code>clippy</code></a>,
it is recommended to use the following command:</p>
<pre><code class="language-console">$ cargo clippy --all --all-targets --all-features -- -D warnings
</code></pre>
<p>Please note the <code>--all-features</code> flag: it is used because we need to enable the <code>test</code> feature
to make lints fully work, for which <code>--all-features</code> happens to be a convenient shortcut.</p>
<p>The <code>test</code> feature is required because <code>rustup</code> uses
<a href="https://doc.rust-lang.org/cargo/reference/features.html">cargo features</a> to
<a href="https://doc.rust-lang.org/reference/conditional-compilation.html">conditionally compile</a>
support code for integration tests, as <code>#[cfg(test)]</code> is only available for unit tests.</p>
<p>If you encounter an issue or wish to speed up the initial analysis, you could also try
activating only the <code>test</code> feature by replacing <code>--all-features</code> with <code>--features=test</code>.</p>
<h2 id="rust-analyzer"><a class="header" href="#rust-analyzer">Rust-Analyzer</a></h2>
<p>When checking the codebase using <code>rust-analyzer</code>, the first thing to do remains unchanged:
enabling the features.</p>
<p>This is done by setting the <code>rust-analyzer.cargo.features</code> property to <code>"all"</code>.</p>
<p>For example, if you are using <code>rust-analyzer</code> within VSCode, you would want to
add the following to your project’s <code>.vscode/settings.json</code><sup class="footnote-reference"><a href="#vscode-global-cfg">1</a></sup>:</p>
<pre><code class="language-jsonc">"rust-analyzer.cargo.features": "all",
</code></pre>
<div class="footnote-definition" id="vscode-global-cfg"><sup class="footnote-definition-label">1</sup>
<p>Alternatively, if you want to apply the configuration to all your Rust projects,
you can add it to your global configuration at <code>~/.config/Code/User/settings.json</code> instead.</p>
</div>
<p>Alternatively, if you want to enable the <code>test</code> feature only, you should set the
following instead:</p>
<pre><code class="language-jsonc">"rust-analyzer.cargo.features": ["test"]
</code></pre>
<p>Next, as <code>rust-analyzer</code> depends on <code>cargo check</code> by default, it is also recommended to
enable the <code>cargo clippy</code> integration by adding the following:</p>
<pre><code class="language-jsonc">"rust-analyzer.check.command": "clippy",
</code></pre>
<p>You might also want to refer to the
<a href="https://rust-analyzer.github.io/manual.html#configuration"><code>rust-analyzer</code> manual</a>
for more details on properly setting up <code>rust-analyzer</code> in your IDE of choice.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="coding-standards"><a class="header" href="#coding-standards">Coding standards</a></h1>
<p>Generally we just follow good sensible Rust practices, clippy and so forth.
However there are some practices we’ve agreed on that are not machine-enforced;
meeting those requirements in a PR will make it easier to merge.</p>
<h2 id="atomic-commits"><a class="header" href="#atomic-commits">Atomic commits</a></h2>
<p>We use atomic commits across the repo. Each commit should represent a single unit of change.
You can read more about atomic commits <a href="https://www.aleksandrhovhannisyan.com/blog/atomic-git-commits">here</a>.</p>
<h2 id="import-grouping"><a class="header" href="#import-grouping">Import grouping</a></h2>
<p>In each file the imports should be grouped into at most 4 groups in the
following order:</p>
<ol>
<li>stdlib</li>
<li>non-repository local crates</li>
<li>repository local other crates</li>
<li>this crate</li>
</ol>
<p>Separate each group with a blank line, and rustfmt will sort into a canonical
order. Any file that is not grouped like this can be rearranged whenever the
file is touched - we’re not precious about having it done in a separate commit,
though that is helpful.</p>
<h2 id="no-direct-use-of-process-state-outside-rustupprocess"><a class="header" href="#no-direct-use-of-process-state-outside-rustupprocess">No direct use of process state outside rustup::process</a></h2>
<p>The <code>rustup::process</code> module abstracts the global state that is
<code>std::env::args</code>, <code>std::env::vars</code>, <code>std::io::std*</code> and <code>std::env::current_dir</code>
permitting threaded tests of the CLI logic; use the relevant methods of the
<code>rustup::process::Process</code> type rather than those APIs directly.
Usually, a <code>process: &amp;Process</code> variable will be available to you in the current context.
For example, it could be in the form of a parameter of the current function,
or a field of a <code>Cfg</code> instance, etc.</p>
<h2 id="clippy-lints"><a class="header" href="#clippy-lints">Clippy lints</a></h2>
<p>We do not enforce lint status in the checks done by GitHub Actions, because
clippy is a moving target that can make it hard to merge for little benefit.</p>
<p>We do ask that contributors keep the clippy status clean themselves.</p>
<p>Minimally, run <code>cargo clippy --all --all-targets --features test -- -D warnings</code> before
submitting code.</p>
<p>If possible, adding <code>--all-features</code> to the command is useful, but will require
additional dependencies like <code>libcurl-dev</code>.</p>
<p>Regular contributors or contributors to particularly OS-specific code should
also make sure that their clippy checking is done on at least Linux and Windows,
as OS-conditional code is a common source of unused imports and other small
lints, which can build up over time.</p>
<p>For developers using BSD/Linux/Mac OS, there are Windows VM’s suitable for such
development tasks for use with virtualbox and other hypervisors are downloadable
from
<a href="https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/">Microsoft</a>.
Similarly, there are many Linux and Unix operating systems images available for
developers whose usual operating system is Windows. Currently Rustup has no Mac
OS specific code, so there should be no need to worry about Mac VM images.</p>
<p>Clippy is also run in GitHub Actions, in the <code>General Checks / Checks</code> build
task, but not currently run per-platform, which means there is no way to find
out the status of clippy per platform without running it on that platform as a
developer.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="version-numbers"><a class="header" href="#version-numbers">Version numbers</a></h1>
<p>If you ever see a released version of rustup which has <code>::</code> in its version string
then something went wrong with the CI and that needs to be addressed.</p>
<p>We use <code>git-testament</code> to construct our version strings. This records, as a
struct, details of the git commit, tag description, and also an indication
of modifications to the working tree present when the binary was compiled.</p>
<p>During normal development you may get information from invoking <code>rustup --version</code>
which looks like <code>rustup-init 1.18.3+15 (a54051502 2019-05-26)</code> or even
<code>rustup-init 1.18.3+15 (a54051502 2019-05-26) dirty 1 modification</code>.</p>
<p>The first part is always the binary name as per <code>clap</code>’s normal operation. The
version number is a combination of the most recent tag in the git repo, and the
number of commits since that tag. The parenthesised information is, naturally,
the SHA of the most recent commit and the date of that commit. If the indication
of a dirty tree is present, the number of changes is indicated. This combines
adds, deletes, modifies, and unknown entries.</p>
<p>You can request further information of a <code>rustup</code> binary with the
<code>rustup dump-testament</code> hidden command. It produces output of the form:</p>
<pre><code class="language-shell">$ rustup dump-testament
Rustup version renders as: 1.18.3+15 (a54051502 2019-05-26) dirty 1 modification
Current crate version: 1.18.3
Built from branch: kinnison/version-strings
Commit info: 1.18.3+15 (a54051502 2019-05-26)
Modified: CONTRIBUTING.md
</code></pre>
<p>This can be handy when you are testing development versions on your PC
and cannot remember exactly which version you had installed, or if you have given
a development copy (or instruction to build such) to a user, and wish to have them
confirm <em>exactly</em> what they are using.</p>
<p>Finally, we tell <code>git-testament</code> that we trust the <code>stable</code> branch to carry
releases. If the build is being performed when not on the <code>stable</code> branch, and
the tag and <code>CARGO_PKG_VERSION</code> differ, then the short version string will include
both, in the form <code>rustup-init 1.18.3 :: 1.18.2+99 (a54051502 2019-05-26)</code> which
indicates the crate version before the rest of the commit.
On the other hand, if the build was on the <code>stable</code> branch then regardless
of the tag information, providing the commit was clean, the version is
always replaced by the crate version. The <code>dump-testament</code> hidden command can
reveal the truth however.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="making-a-release"><a class="header" href="#making-a-release">Making a release</a></h1>
<p>Before making a release, ensure that <code>rustup-init.sh</code> is behaving correctly,
and that you’re satisfied that nothing in the ecosystem is breaking because
of the update. A useful set of things to check includes verifying that
real-world toolchains install okay, and that <code>rust-analyzer</code> isn’t broken by
the release. While it’s not our responsibility if they depend on non-stable
APIs, we should behave well if we can.</p>
<p>As a maintainer, you have two options to choose from when cutting a new
release: a beta release or an official release.
The main difference between the two is that they use different values for
the <code>RUSTUP_UPDATE_ROOT</code> environment variable:</p>
<ul>
<li>A beta release is deployed on <code>https://dev-static.rust-lang.org/rustup</code>.</li>
<li>An official release is deployed on <code>https://static.rust-lang.org/rustup</code>.</li>
</ul>
<p>By switching between those two values, Rustup effectively provides two “self
update channels”, making beta testing possible with <code>rustup self update</code>.</p>
<p>Producing the final release artifacts is a bit involved because of the way
Rustup is distributed.
Below is a list of things to be done in order to cut a new [b]eta release
or an official [r]elease:</p>
<ol>
<li>[b/r] In a separate PR:
<ol>
<li>If the version strings in <code>Cargo.toml</code>s haven’t been updated:
<ul>
<li>Decide what the new version number <code>$VER_NUM</code> should be.
<blockquote>
<p><strong>Note:</strong> We always increment the <em>minor</em> number unless:</p>
<ul>
<li>A major incompatibility has been introduced in this release:
increment the <em>major</em> number instead.</li>
<li>This release is a hotfix because the last one had a defect:
increment the <em>patch</em> number instead.</li>
</ul>
</blockquote>
</li>
<li>Update <code>Cargo.toml</code> and <code>download/Cargo.toml</code> to have that same new
version number, then run <code>cargo build</code> and review <code>Cargo.lock</code> changes.
If all looks well, make a commit.</li>
</ul>
</li>
<li>Update <code>CHANGELOG.md</code> accordingly if necessary.</li>
</ol>
</li>
<li>[b/r] After merging the PR made in step 1, in a separate PR:
<ol>
<li>Update the commit shasum in <code>rustup-init.sh</code> to match the latest commit
on <code>master</code>.</li>
</ol>
</li>
<li>[b/r] After merging the PR made in step 2, sync <code>master</code> to <code>stable</code> using
<code>--ff-only</code>:
<ul>
<li><code>git fetch origin master:master</code></li>
<li><code>git checkout stable &amp;&amp; git merge --ff-only master</code></li>
<li><code>git push origin HEAD:stable</code></li>
</ul>
</li>
<li>[b/r] While you wait for green CI on <code>stable</code>, double-check the
functionality of <code>rustup-init.sh</code> and <code>rustup-init</code> just in case.</li>
<li>[b/r] Ensure all of CI is green on the <code>stable</code> branch.
Once it is, check through a representative proportion of the builds looking
for the reported version statements to ensure that
we definitely built something cleanly which reports as the right version
number when run <code>--version</code>.</li>
<li>[r] Make a new PR to the <a href="https://github.com/rust-lang/blog.rust-lang.org">Rust Blog</a> adding a new release announcement post.</li>
<li>[b/r] Ping someone in the release team to perform the actual release.
They can find instructions in <code>ci/sync-dist.py</code>.
<blockquote>
<p><strong>Note:</strong> Some manual testing occurs here, so hopefully they’ll catch
anything egregious in which case abort the change and roll back.</p>
</blockquote>
</li>
<li>[b] Once the beta release has happened, post a new topic named “Seeking beta
testers for Rustup $VER_NUM” on the <a href="https://internals.rust-lang.org">Internals Forum</a>.</li>
<li>[r] Once the official release has happened, prepare and push a tag on the
latest <code>stable</code> commit.
<ul>
<li><code>git tag -as $VER_NUM -m $VER_NUM</code> (optionally without <code>-s</code> if not GPG
signing the tag)</li>
<li><code>git push origin $VER_NUM</code></li>
</ul>
</li>
</ol>
<div style="break-before: page; page-break-before: always;"></div><h1 id="developer-tips-and-tricks"><a class="header" href="#developer-tips-and-tricks">Developer tips and tricks</a></h1>
<h2 id="rustup_force_arg0"><a class="header" href="#rustup_force_arg0"><code>RUSTUP_FORCE_ARG0</code></a></h2>
<p>The environment variable <code>RUSTUP_FORCE_ARG0</code> can be used to get rustup to think
it’s a particular binary, rather than e.g. copying it, symlinking it or other
tricks with exec. This is handy when testing particular code paths from cargo
run.</p>
<pre><code class="language-shell">RUSTUP_FORCE_ARG0=rustup cargo run -- uninstall nightly
</code></pre>
<h2 id="rustup_backtrack_limit"><a class="header" href="#rustup_backtrack_limit"><code>RUSTUP_BACKTRACK_LIMIT</code></a></h2>
<p>If it’s necessary to alter the backtracking limit from the default of half
a release cycle for some reason, you can set the <code>RUSTUP_BACKTRACK_LIMIT</code>
environment variable. If this is unparsable as an <code>i32</code> or if it’s absent
then the default of 21 days (half a cycle) is used. If it parses and is less
than 1, it is clamped to 1 at minimum.</p>
<p>This is not meant for use by users, but can be suggested in diagnosing an issue
should one arise with the backtrack limits.</p>
<h2 id="rustup_max_retries"><a class="header" href="#rustup_max_retries"><code>RUSTUP_MAX_RETRIES</code></a></h2>
<p>When downloading a file, rustup will retry the download a number of times. The
default is 3 times, but if this variable is set to a valid usize then it is the
max retry count. A value of <code>0</code> means no retries, thus the default of <code>3</code> will
mean a download is tried a total of four times before failing out.</p>
<h2 id="rustup_backtrace"><a class="header" href="#rustup_backtrace"><code>RUSTUP_BACKTRACE</code></a></h2>
<p>By default while running tests, we unset some environment variables that will
break our testing (like <code>RUSTUP_TOOLCHAIN</code>, <code>SHELL</code>, <code>ZDOTDIR</code>, <code>RUST_BACKTRACE</code>).
But if you want to debug locally, you may need backtrace. <code>RUSTUP_BACKTRACE</code>
is used like <code>RUST_BACKTRACE</code> to enable backtraces of failed tests.</p>
<p><strong>NOTE</strong>: This is a backtrace for the test, not for any subprocess invocation of
rustup process running in the test</p>
<pre><code class="language-bash">$ RUSTUP_BACKTRACE=1 cargo test --release --test cli-v1 -- remove_toolchain_then_add_again
    Finished release [optimized] target(s) in 0.38s
     Running target\release\deps\cli_v1-1f29f824792f6dc1.exe

running 1 test
test remove_toolchain_then_add_again ... FAILED

failures:

---- remove_toolchain_then_add_again stdout ----
thread 'remove_toolchain_then_add_again' panicked at 'called `Result::unwrap()` on an `Err` value: Os { code: 1142, kind: Other, message: "An attempt was made to create more links on a file than the file system supports." }', src\libcore\result.rs:999:5
stack backtrace:
   0: backtrace::backtrace::trace_unsynchronized
             at C:\Users\appveyor\.cargo\registry\src\github.com-1ecc6299db9ec823\backtrace-0.3.29\src\backtrace\mod.rs:66
   1: std::sys_common::backtrace::_print
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\sys_common\backtrace.rs:47
   2: std::sys_common::backtrace::print
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\sys_common\backtrace.rs:36
   3: std::panicking::default_hook::{{closure}}
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\panicking.rs:198
   4: std::panicking::default_hook
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\panicking.rs:209
   5: std::panicking::rust_panic_with_hook
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\panicking.rs:475
   6: std::panicking::continue_panic_fmt
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\panicking.rs:382
   7: std::panicking::rust_begin_panic
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libstd\panicking.rs:309
   8: core::panicking::panic_fmt
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libcore\panicking.rs:85
   9: core::result::unwrap_failed
  10: cli_v1::mock::clitools::test
  11: alloc::boxed::{{impl}}::call_once&lt;(),FnOnce&lt;()&gt;&gt;
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\src\liballoc\boxed.rs:746
  12: panic_unwind::__rust_maybe_catch_panic
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libpanic_unwind\lib.rs:82
  13: std::panicking::try
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\src\libstd\panicking.rs:273
  14: std::panic::catch_unwind
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\src\libstd\panic.rs:388
  15: test::run_test::run_test_inner::{{closure}}
             at /rustc/de02101e6d949c4a9040211e9ce8c488a997497e\/src\libtest\lib.rs:1466
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.


failures:
    remove_toolchain_then_add_again

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 26 filtered out

error: test failed, to rerun pass '--test cli-v1'
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="tracing"><a class="header" href="#tracing">Tracing</a></h1>
<p>Similar to other tools in the Rust ecosystem like rustc and cargo,
rustup also provides observability/logging features via the <code>tracing</code> crate.</p>
<p>The verbosity of logs is controlled via the <code>RUSTUP_LOG</code> environment
variable using <code>tracing_subscriber</code>’s <a href="https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives">directive syntax</a>.</p>
<h2 id="console-based-tracing"><a class="header" href="#console-based-tracing">Console-based tracing</a></h2>
<p>A <code>tracing_subscriber</code> that prints log lines directly to <code>stderr</code> is directly
available in the prebuilt version of rustup since v1.28.0.</p>
<p>For historical reasons, if <code>RUSTUP_LOG</code> is not set, this subscriber will print
the log lines in a format that mimics the “legacy” <code>stderr</code> output in older
versions of rustup:</p>
<pre><code class="language-console">&gt; rustup default stable
info: using existing install for 'stable-aarch64-apple-darwin'
info: default toolchain set to 'stable-aarch64-apple-darwin'

  stable-aarch64-apple-darwin unchanged - rustc 1.79.0 (129f3b996 2024-06-10)
</code></pre>
<p>However, once <code>RUSTUP_LOG</code> is set to any value, rustup’s “custom logging mode” will
be activated, and <code>tracing_subscriber</code>’s builtin output format will be used instead:</p>
<pre><code class="language-console">&gt; RUSTUP_LOG=trace rustup default stable
2024-06-16T12:08:48.732894Z  INFO rustup::cli::common: using existing install for 'stable-aarch64-apple-darwin'
2024-06-16T12:08:48.739232Z  INFO rustup::cli::common: default toolchain set to 'stable-aarch64-apple-darwin'

  stable-aarch64-apple-darwin unchanged - rustc 1.79.0 (129f3b996 2024-06-10)
</code></pre>
<p>Please note that since <code>RUSTUP_LOG=trace</code> essentially accepts log lines from
all possible sources, you might sometimes see log lines coming from rustup’s
dependencies, such as <code>hyper_util</code> in the following example:</p>
<pre><code class="language-console">&gt; RUSTUP_LOG=trace rustup update
[..]
2024-06-16T12:12:45.569428Z TRACE hyper_util::client::legacy::client: http1 handshake complete, spawning background dispatcher task
2024-06-16T12:12:45.648682Z TRACE hyper_util::client::legacy::pool: pool dropped, dropping pooled (("https", static.rust-lang.org))

   stable-aarch64-apple-darwin unchanged - rustc 1.79.0 (129f3b996 2024-06-10)
  nightly-aarch64-apple-darwin unchanged - rustc 1.81.0-nightly (3cf924b93 2024-06-15)

2024-06-16T12:12:45.693350Z  INFO rustup::cli::rustup_mode: cleaning up downloads &amp; tmp directories
</code></pre>
<p>It is also possible to limit the sources of the log lines and the desired
max level for each source. For example, set <code>RUSTUP_LOG=rustup=DEBUG</code> to
receive log lines only from <code>rustup</code> itself with a max verbosity of <code>DEBUG</code>.</p>
<h2 id="opentelemetry-tracing"><a class="header" href="#opentelemetry-tracing">Opentelemetry tracing</a></h2>
<blockquote>
<p><strong>Prerequisites:</strong> Before following the instructions in this section,
<code>protoc</code> must be installed, which can be downloaded from GitHub
or installed via a package manager.</p>
</blockquote>
<p>The feature <code>otel</code> can be used when building rustup to turn on Opentelemetry
tracing with an OLTP GRPC exporter.</p>
<p>This can be very useful for diagnosing performance or correctness issues in more
complicated scenarios.</p>
<p>The normal <a href="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md">OTLP environment
variables</a>
can be used to customise its behaviour, but often the simplest thing is to just
run a Jaeger docker container on the same host:</p>
<pre><code class="language-sh">docker run -d --name jaeger   -e COLLECTOR_ZIPKIN_HOST_PORT=:9411   -e COLLECTOR_OTLP_ENABLED=true   -p 6831:6831/udp   -p 6832:6832/udp   -p 5778:5778   -p 16686:16686   -p 4317:4317   -p 4318:4318   -p 14250:14250   -p 14268:14268   -p 14269:14269   -p 9411:9411   jaegertracing/all-in-one:latest
</code></pre>
<p>Then build <code>rustup-init</code> with tracing:</p>
<pre><code class="language-sh">cargo build --features=otel
</code></pre>
<p>Run the operation you want to analyze. For example, we can now run <code>rustup show</code> with tracing:</p>
<pre><code class="language-sh">RUSTUP_FORCE_ARG0="rustup" ./target/debug/rustup-init show
</code></pre>
<p>And <a href="http://localhost:16686/search?service=rustup">look in Jaeger for a trace</a>.</p>
<p>Tracing can also be used in tests to get a trace of the operations taken during the test.
To use this feature, build the project with <code>--features=otel,test</code>.</p>
<h3 id="adding-instrumentation"><a class="header" href="#adding-instrumentation">Adding instrumentation</a></h3>
<p>The <code>otel</code> feature uses conditional compilation to only add function instrument
when enabled. Instrumenting a currently uninstrumented function is mostly simply
done like so:</p>
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
</span><span class="boring">fn main() {
</span>#[tracing::instrument(level = "trace", err(level = "trace"), skip_all)]
<span class="boring">}</span></code></pre></pre>
<p><code>skip_all</code> is not required, but some core structs don’t implement Debug yet, and
others have a lot of output in Debug : tracing adds some overheads, so keeping
spans lightweight can help avoid frequency bias in the results - where
parameters with large debug in frequently called functions show up as much
slower than they are.</p>
<p>Some good general heuristics:</p>
<ul>
<li>Do instrument slow blocking functions</li>
<li>Do instrument functions with many callers or that call many different things,
as these tend to help figure the puzzle of what-is-happening</li>
<li>Default to not instrumenting thin shim functions (or at least, only instrument
them temporarily while figuring out the shape of a problem)</li>
<li>Be way of debug build timing - release optimisations make a huge difference,
though debug is a lot faster to iterate on. If something isn’t a problem in
release don’t pay it too much heed in debug.</li>
</ul>

                    </main>

                    <nav class="nav-wrapper" aria-label="Page navigation">
                        <!-- Mobile navigation buttons -->


                        <div style="clear: both"></div>
                    </nav>
                </div>
            </div>

            <nav class="nav-wide-wrapper" aria-label="Page navigation">

            </nav>

        </div>




        <script>
            window.playground_copyable = true;
        </script>


        <script src="elasticlunr.min.js"></script>
        <script src="mark.min.js"></script>
        <script src="searcher.js"></script>

        <script src="clipboard.min.js"></script>
        <script src="highlight.js"></script>
        <script src="book.js"></script>

        <!-- Custom JS scripts -->

        <script>
        window.addEventListener('load', function() {
            window.setTimeout(window.print, 100);
        });
        </script>

    </div>
    </body>
</html>
